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Subject: New list command - Revision 1 


The 


design of the new list command proposed in MTB-125 has been 


modified as a result of the design review. The changes made _ to 


the 


original proposal are summarized below. A draft MPM writeup 


of the revised design is attached. 


Changes to Proposed Features 


1. 


The ability to control the order in which entry types are 
listed, by typing their corresponding control arguments in 
the desired order, has been removed. It was felt that the 
undesirability of order-dependent eontrol arguments 
outweichs any advantage of being able to vary the order of 
tne listing. 


The ehange to the default order remains, however, and entry 
types will now be listed in the order: segments, 
multisegment-files, directories, and links. 


The method of specifying which columns are to be printed has 
been changed slightly. In the original proposal, givins the 
control argument corresponding to a column caused that 
eolumn, plus all those to its right, to be printed, unless 
-~brief was also given. The default was -mode, causing mode, 
records, and names to be listed by default. 


In the revised proposal, by default, the names, records, and 
moce columns will be printed, but if -brief, or any of the 
eontrol arguments corresponding to the default columns, is 
given, the default will be overridden, and only the names 
eolumn (which is always vrinted), plus any ecolurns vared 
explicitly by control areuments, will be printed. 


Fither or both dates will be printed, if their corresponding 
control arguments are given. Use of the date control 
arguments will have no effect on whether or not anv of the 
default columns are printed. 


The method of specifying whieh column to sort on was 
changed. Instead of typing one of the column-name control 
arguments after -sort xe) request sorting on fhe 
eorresponding column, it will now be necessary to tvne a 
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keyword that does not begin with a minus sign. The kevwords 
will be spelled the same as the column-name control 
arguments (except for the leading minus signs), and both the 
long and short forms will be accented. It was felt that a 
value following a control argument should not have the same 
form as a control argument. 


Tne default of sorting on the leftmost column, when -sort is 
given without being followed by a column specification, has 
been changed. If one of the sort keywords follows -sort, 
the listing will be sorted by the specified column. However, | 
if none of the keywords follows -sort, a default column will 

be determined as follows: if neither date is being printed, 
sort by name; if one of the dates is being printed, sort by 
that date; if both dates are being printed, sort by dtm. 


New Restriction 


New 


Wa 


ae 


The ability to give more than one -pathname argument (to 
specify that more than one directory be listed), will be 
removed from the command. A single -pathname argument, 
anywhere on the line, will cause only that directory to be 
listed, and, naturally, all starnames given on the command 
line will be searched for in that directorv. The default 
wili still be to list the working directory. The purpose of 
this is to eliminate all order-denendent control arguments. 


Features 


The ability to sort by mode has been added. 


A new argument, -match, has been added, to request that, for 
multiply-named entries, only those names that match a 
starname be printed. (This is what the current list command 
does by default, but the default is being changed to print 
all names on the entries selected for listing.) 


New control arguments: -from (-fm) date_time and -to 
date time have been added, to reauest that only entries 
having dtm or dtu between the specified dates be printed. 
dtm will be used for this purpose in all cases except when 
dtu is being printed or sorted on, and dtm is being neither 
printed nor sorted on. 


It -from is omitted, entries from the earliest date_time 
thru the -to date_time will be printed. If -to is omitted, 
entries from the -from date_time thru the current date_time 
will be printed. The given date _times must be strings 
acceptable to convert_date_to_binary_, and the -to date_time 
must be later than the -from date_time. 


A new control argument, -exclude (-ex) has been added, to 
specify that entries matching a given starname be excluded 
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from the listing, rather than being ineluded. This new 
argument will precede each starname whose matching entries 
are to be excluded. It will be possible to give both include 
and exclude starnames on the same command line, and only 
entries that meet both criteria will be listed. That is, 
entries matching any of the exclude starnames ill be 
excluded from the listing, and from the ones that remain, 
those that match any of the include starnames will be 
listed. 


Documentation 


The attached MPM writeup says that the default order, when 
no sorting is specified, is the order in which entries are 
found in the directory, and that -reverse without -sort will 
reverse this order. 


Some readers of this MTB might interpret this as a chanre in 
the present operation of the list command, knowing that new 
entries are added to the end of a directory, with the oldest 
entries remaining at the beginning, and the list command 
deliberately reverses this order, printing the newest 
entries first. In fact, the oneration of the command is not 
changing, but the MPM writeup is being simplified by the 
removal of the above detail. 
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The list command prints information about entries in a single 
directory. Arguments allow the user to specify the directory to 
be listed, the entry types, names, and dates for which 


information is to be printed, the amount of information to be 
printed for each entry, and the order in which entries are to be 
Listed. 


The defauit, when no arguments are given, is to list files 
(sepments and multi-segement files) of all names, in the working 
directory. For each entry, the mode, records used, primary name, 
and any additional names, will be printed. The two entry types 
will be listed in the order: serments, multi-serment files; 
within each entry type, entries will be printed in the order in 
which they are found in the cirectory. Precedings the listing of 
each entry type will be a line giving the total number of entries 
of that type and the total records used. . 


USAGE: List -entry_names- -control_arguments- 


1) entry_names are the (optional) names of entries to be 
Listed. If entry names are given, only 
entries having at least one name matchine one 
of the entry names will be listed. The star 
convention may be used in the entry names. 
Except when the -exclude control argument is 
used, the positions of the entrv names 
(before, after, or among the eontrol 
arguments) have no significance. 


2) control_arguments may be chosen from the following: 


-~Dathname dir_path 
-pon dir_path eauses the directory dir_path to be listed, 
i 


© 
tead of the working directory. 


The following control arguments are used to specifv the entry 
types to be listed: 


~segment, -sm print information about segments. 


-multisegment_file, 
-msf print information about multi-segment files. 


-file, -f print information about files (i.e., segments 
and multi-segment files, in that order). This 
is the default. 


-direetory, -dr print information about directories. 


-branch, -br print information about branches Ci Gis 
segments, multi-segment files, and 
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directories, in that order). 
-iink, -1lk print information about links. 


“all, -a print information about all entry types 
(segments, multi-segment files, directories, 
and links, in that order). 


The following control arguments are used to specify whether 
totals information, or detailed information for each entrv, or 
both, should be printed: | 


atotal .-=tt print only the heading lines givine total 
entries and total records used, for each 
entry type specified. | 


~no_header, -nhe omit the heading lines (ihien are printed by 
default when detailed information about each 
entry is being printed). 


The default is to print totals information, plus detailed 
information for each entry. When detailed information is being 
printed, it is arranged in columns, in the order (from left to 
right): date-time modified, date-time used, mode, records used, 
names, name count. By default, only the mode, records, and names 
columns are printed. If the -brief control argument (see below) 
or any of the control arguments corresponding to these default 
columns is given, then this default is overridden, and only the 
names column, plus any columns selected explicitly by control 
arguments, will be printed. 


The following control arguments are used to specify which columns 
should be printed: 


~name, =<nm print the names column. 
-record, -rec print the records column. 
-mode, -md print the mode column. 


-date_time_used, 
edtu print the date-time used column. 


_-date_time_modified, 
-dtm print the date-time modified column. 


The following control arguments are used to specify the ovrinting 
of information about multiply-named entries: 


-primary, -pri print the primary name, but not the 
additional names, of multiply-named entries. 
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-match print only those names that match one of the 
given starnames. 


The default is to print all of the names of multiply-named 
entries. 
-count, -ct for multiply-named entries, print the total 


number of names. 


The following control arguments are used to decrease the amount 
of information printed, or cause it to be printed in a more 
compact format: os 


-~brief, -bf This argument has two meanings, depending on 
whether or not detailed information is being 
printed. If just totals information is being 
printed, this argument will cause the totals 
information for all selected entry tvnes to 
be abbreviated and printed on a4 single line. 
Otherwise, it will suppress the orintine of 
the default columns when they are not 
explicitly named in control ‘arguments. For 
example, list -dtu -brief will cause names 
and date_time_used, but not mode and records, 
to be printed. 


-short, -sh print link pathnames starting two spaces 
after their entry names, instead of aligning 
them in column 35. 


Tne items: mode, records, and date_time_used have no meaning for 
links, and there is an additional item, link_path, associated 
with each link. There is no control argument to specifv that 
link _path should be printed. It will be printed in all cases 
except the following: 


1) when only totals information is being printed; 
2) when the only column being printed is the names column; 
3) when the -brief control argument is given. 


The following control arguments specify the order in which 
entries will be printed, within each entry type: 


-sort sort_key sort entries according to either name, 
records, mode, date time_used, or 
date_time_modified, as specifed bv the 
sort_key, or by the default described below. 


The sort_key can be one of the following keywords: 
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Name, nm sort entries by primary name. 
record, rec sort entries by records used (lareest first). 
mode, md sort entries by mode. 
date_time_used, 7 
dtu sort entries by date_time_used {most recent 


first). 


date _time_modified, 
dtm sort entries by date_time_modified (most 
recent first). 


It sort_key is omitted, the default column on which to sort is 
determined as follows: if neither date is being printed, sort. by 
primary name; if one of the dates is being printed, sort by that 
date; if both dates are being printed, sort by date-time 
modified. 


Links ean only be sorted by name or date-time modified. When 
sorting by any other column is specified, links will remain in 
the order in which they are found in the directory. 


If -sort is not given, entries will be printed in the order in 
which they are found in the directory. 


-reverse, -rv This argument is used to reverse the order in 
which entries are printed. If -sort is also 
given, the sort will be reversed. Otherwise 
entries will be printed in the reverse of the 
order in which they are. found in the 
directory. 


The following control arguments ae used to specify that only a 
subset of all entries in the directory be listed: 


-exclude entry_name 

-ex entry_name do not list any entries that ha 
matches entry_name. The star oa 
be used in entry_name. 


ve a 
onven* 


Multiple exclude entry names can be given 
(each immediately preceded by the -exclude 
control argument). They will operate tosether 
With include entry names (those not preceded 
by -exclude), to limit the entries listed. 
All entries having a name that matches anv of 
the exclude entry names will be excluded from 
the listing, and from the entries that 
remain, all those that have a name matching 
any of the include entry names will he 
listed. 
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The followings control arguments are used to limit the entries 
listed to those having date-times (either date-time modified or 


date-time used) before or after specified date-times. The 
date-time that is used in this comparison will be date-time 


Oo LA 
modified, in all cases except when date-time used is being 
printed or sorted on, and date-time modified is neither being 
printed nor sorted on, in which case, date-time used will be used 
in this comparison. 


-from date-time 

-~tm date-time do not List entries whose date-time (selected 
as described above) is before the specified 
date-time. 


-to date-time do not list entries whose date-time (selected 
as described above) is after the svecified 
date-time. 


It both are given, the from date-time must be earlier than the to 
date-time. Tne value after -from or -to must be a string 
acceptable to the convert_date_to_binary_ subroutine, descerited 
in MPM Volume III (Subroutines). If the date-time string contains 
blanks, it must be enclosed in quotation marks. Note that the 


from and to values are date-times, and that the default time 
supplied by convert _date_ to _binary_, when only a date is given, 
13: .MitdnEeent. Therefore, to list entries modified on a certain 
date, use -from that_date -to next_date. 


EXAMPLES: 

List -pri -ct 
lists all files in the working directory; for multinlv-named 
files, the primary name is printed, but not any of the secondary 
names, and the total number of names that the rile has is printed 
after the primary name, on the same line. In addition to the 
names column, the mode and records used columns are printed. 
(This is the default, and it will not be mentioned in the 
examples below, when only the default columns are printed.) 

list -sm *.* -ex *.pl11 


lists all the segments in the working directorv having 
two-component names whose second component is not "pli". 


list -ex *,* 


lists all the files in the workine directory havine other than 
two-component names. 


list -dtm -sort 
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lists all files in the working directory, sorted by date-time 
modified. Tne date-time modified column is printed, in addition 
to the mode, records, and names columns. 

list =-name -sort dtm 


lists all files in the working directory, sorted by date-time 
modified. Only the file names are printed. 


list -sm -name -pri -nhe 


lists the primary name of each segment in the working directory, 
without printing a heading line or other extraneous lines. 


list -mode -pri 


lists the mode and primary name of each file in the working 
directory. 


